home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / net / omniORB-2.5.0-src.tar.gz / omniORB-2.5.0-src.tar / omniORB_2.5.0 / README.unix < prev    next >
Text File  |  1998-02-05  |  10KB  |  244 lines
  1. This file contains information on installing, building and using omniORB2
  2. on Unix platforms. 
  3.  
  4. If you are upgrading from 2.2.0, do not miss the important information about
  5. omniNames at the end of this note.
  6.  
  7. Unless specified otherwise, the information applies to all Unix
  8. platforms. Linux users should also consult the file README.Linux.
  9. Users intented to use egcs or gcc should also read README.egcs and README.gcc
  10.  
  11. omniORB2 has been tested on the following Unix platforms:
  12.  
  13.     Solaris 2.5 / Sun SparcCompiler C++ version 4.2
  14.     Digital Unix 3.2 / DEC C++ compiler version 5.5
  15.     x86 Linux 2.0 / GNU C++ 2.7.2 / Linuxthreads 0.5 (RedHat 4.2)
  16.  
  17.     alpha Linux 2.0 / egcs-1.0+thread_safe_eh_patch / glibc 2.0 (RedHat 5.0)
  18.     x86 Linux 2.0 / egcs-1.0+thread_safe_eh_patch / glibc 2.0 (Redhat 5.0)
  19.  
  20. It has also been tested by external contributors on the following platforms:
  21.  
  22.   o IBM AIX 4.2/ IBM C Set++ 3.1.4
  23.   o HPUX 10.20/ aC++ (B3910 A.01.04)
  24.   o NextStep 3.3/ gcc-2.7.2
  25.  
  26.   o IBM AIX 4.2/ egcs-1.0+thread_safe_eh_patch
  27.  
  28. Roadmap
  29. =======
  30.  
  31. The directory structure of this distribution looks as follows:
  32.  
  33. ./doc                             : omniORB2 documentation
  34. ./man                             : omniORB2 manual pages
  35. ./mk                              : make configuration files
  36. ./config                          : configuration files for target platform
  37. ./include                         : include files
  38. ./src                             : source files
  39. ./src/lib/omnithread              : source files for the omnithread library
  40. ./src/lib/omniORB2                : source files for the ORB runtime library
  41. ./src/tool/omniidl2               : source files for the IDL compiler
  42. ./src/appl/omniNames              : source files for the COS Naming service
  43. ./src/appl/utils                  : source files for utilities
  44. ./src/examples                    : source files for examples
  45.  
  46. If this is a pre-compiled binary distribution, the binaries are located in the
  47. following directories:
  48.  
  49. ./lib                             : static and shared libraries
  50. ./bin                             : executables
  51.  
  52.  
  53. Configuration
  54. =============
  55.  
  56.   1. select the appropriate platform configuration file
  57.   ------------------------------------------------------
  58.  
  59.   Edit ./config/config.mk to select the appropriate platform file
  60.  
  61.       e.g. For Solaris 2.5 onwards and with Sunspro C++
  62.       
  63.             platform = sun4_sosV_5.5
  64.  
  65.    All the platform files are in ./mk/platforms.
  66.  
  67.  
  68.   2. Building and installing
  69.   --------------------------
  70.  
  71.   The makefiles in this distribution only works with GNUmake. Make sure
  72.   that you have the program installed and invokes it directly.
  73.  
  74.   You can skip this step if this is a pre-compiled binary distribution.
  75.   To build and install everything, go into the directory ./src and type 
  76.   'make export'. If all goes well, the libraries and executables will be
  77.   installed into ./lib/<platform>/ and ./bin/<platform>/.
  78.  
  79.  
  80.   3. add omniORB2 libraries to search path
  81.   ----------------------------------------
  82.  
  83.   Since the shared libraries libomniORB2.so and libomnithread.so are not in
  84.   the directories searched by the dynamic loader by default, you must add 
  85.   the library directory to the search path. For example:
  86.  
  87.     On Solaris 2.5
  88.        $ LD_LIBRARY_PATH=<absolute pathname of ./lib/sun4_sosV_5.5>
  89.        $ export LD_LIBRARY_PATH
  90.  
  91.  
  92.   4. configure the naming service
  93.   -------------------------------
  94.  
  95.   If you are upgrading from 2.2.0, please read the important information about
  96.   omniNames at the end of this note.
  97.  
  98.   You also have to configure the omniORB2 runtime and the naming service,
  99.   consult the user guides in ./doc for details. For a quick start, follow
  100.   these steps:
  101.  
  102.     o Set the environment variable OMNINAMES_LOGDIR to a directory where
  103.       the naming service omniNames can store its data. For example:
  104.           OMNINAMES_LOGDIR=/wib/wob; export OMNINAMES_LOGDIR
  105.  
  106.     o Start omniNames. The binary is in ./bin/<platform>/. For example:
  107.          $ ./bin/sun4_sosV_5.5/omniNames -start 12345 &
  108.       Notice that you have to give as a parameter to the option -start
  109.       the TCP/IP port number omniNames will use to receive IIOP requests.
  110.  
  111.     o omniNames writes the stringified object reference for its root context 
  112.       on standard error. You should copy this string into a file omniORB.cfg.
  113.       The format of the entry is the word NAMESERVICE followed by 
  114.       space and the stringified IOR all on one line.  For example:
  115.   
  116.       NAMESERVICE IOR:00fff71c0000002849444c3a6f6d672e6f72672f436f734e616d696e672f4e616d696e67436f6e746578743a312e300000000001000000000000002c0001000000000012776962626c652e776f62626c652e636f6d0004d20000000c34c35a8305a931a200000001
  117.  
  118.     o Set the environment variable OMNIORB_CONFIG to contain the full
  119.       path name of the file omniORB.cfg. For example,
  120.           OMNIORB_CONFIG=/wib/wob/omniORB.cfg; export OMNIORB_CONFIG
  121.  
  122. Building the examples
  123. =====================
  124.  
  125. You are strongly encouraged to try out the examples provided in ./examples.
  126. Go into ./examples and type 'make all'. Make sure that 'make' is GNUmake
  127. because the makefiles are all GNUmake specific.
  128.  
  129. Study the documentations in ./doc before you run any of the example
  130. programs.
  131.  
  132.  
  133. Writing your own Makefile
  134. =========================
  135.  
  136. The distribution makefiles may be a bit much to digest.
  137. Here is a few tips of what to put into your makefiles to compile omniORB2
  138. programs:
  139.  
  140. 1. Compiler flags:
  141.  
  142. To compile omniORB2 programs correctly, several C++ preprocessor defines
  143. must be specified to identify the target platform.
  144.  
  145. Sun Solaris 2.5     |  __sparc__  __sunos__  __OSVERSION__=5      |
  146. Digital Unix 3.2    |__alpha__  __osf1__   __OSVERSION__=3        |
  147. HPUX 10.x           |__hppa__  __hpux__   __OSVERSION__=10        |
  148. IBM AIX 4.x &       |__aix__  __powerpc__   __OSVERSION__=4       |
  149. Linux 2.0 (x86)     |__x86__    __linux__  __OSVERSION__=2        |
  150. Linux 2.0 (alpha)   |__alpha__    __linux__  __OSVERSION__=2      |
  151. Windows/NT 3.5      |__x86__    __NT__     __OSVERSION__=3  __WIN32__|
  152. Windows/NT 4.0      |__x86__    __NT__     __OSVERSION__=4  __WIN32__|
  153. Windows/95          | __x86__ __WIN32__                            |
  154. OpenVMS 6.x (alpha) |__alpha__    __vms     __OSVERSION__=6        |
  155. OpenVMS 6.x (vax)   |__vax__    __vms     __OSVERSION__=6          |
  156. ATMos 4.0           |__arm__    __atmos__  __OSVERSION__=4         |
  157. NextStep 3.x        |__m68k__  __nextstep__   __OSVERSION__=3      |
  158.  
  159. You should also specify the preprocessor defines (e.g. -D\_REENTRANT) for
  160. compiling multithreaded programs.
  161.  
  162. Have a look at the <platform>.mk file in <top>/mk/platforms. And see what
  163. OMNITHREAD_LIB and OMNIORB2_LIB is set to. 
  164.  
  165. 2. Libraries:
  166.  
  167. The runtime libraries that you have to link to your executables are:
  168.  
  169. libomnithread.so  - omnithread share library
  170. libomniORB2.so    - omniORB2 runtime shared library
  171. libomniLC.so      - lifecycle service runtime shared library
  172.  
  173. One of the following gatekeeper library:
  174.  - libtcpwrapGK.so   - implemented using tcpwrapper
  175.  - libomniGK_stub.a  - dummy stub.
  176.  
  177. Either link with -ltcpwrapGK or -lomniGK_stub but not both.
  178. (At the moment, only linux, solaris and digital unix have tcpwrapGK enabled.)
  179.  
  180. The name of the libraries may be have different suffixes on different
  181. platforms, you can figure it out.
  182.  
  183. 3. IDL compiler:
  184.  
  185. IDL stubs can be compiled like this:
  186.  
  187.   omniidl2 echo.idl
  188.  
  189. The product is the files: echo.hh and echoSK.cc
  190.  
  191.  
  192. Documentation
  193. =============
  194.  
  195. You must read the omniORB2 and the OMNI naming service user guides. Follow
  196. the instructions in the guides to complete the configuration process.
  197.  
  198. Important Change to omniNames for users upgrading from version 2.2.0
  199. ====================================================================
  200.  
  201. Since release 2.4.0, the naming service uses the prefix pragma "omg.org" in 
  202. its IDL. 
  203.  
  204. Unfortunately, this is not compatible on-the-wire with clients that are
  205. linked with the old library, i.e. any programs linked before version 2.4.0
  206. was released.
  207.  
  208. The implications of this change are as follows:
  209.  
  210. a) omniNames built in this release *CANNOT* read the data file of the
  211.    version 2.2.0 omniNames . A new instance must be started from scratch.
  212.    If you start omniNames and tell it to use the old data file, it will 
  213.    certainly crash.
  214.  
  215.    Possible migration path:
  216.      At ORL, we are running the old and the new omniNames in parallel.
  217.      The new instance is setup to run on a different port. Also the
  218.      new tree is built to read by default a different configuration file:
  219.      (/project/omni/var/omniORB_NEW.cfg instead of 
  220.      /project/omni/var/omniORB.cfg) so that a client will pick up the
  221.      IOR of the old or the new omniNames depending on whether it is compiled
  222.      with the old or the new library. When all our services have been
  223.      recompiled, the old omniNames will be withdrawn.
  224.  
  225.  
  226. b) If you want to continue to use the old omniNames, you can undo this
  227.    change with the following steps:
  228.      1. Edit <top>/src/lib/omniORB2/Naming.idl and remove the 
  229.         #pragma prefix "omg.org" line.
  230.      2. Do the same to <top>/idl/Naming.idl.
  231.      3. Remove <top>/include/omniORB2/Naming.hh.
  232.      4. Rebuild everything. You should do a gnumake/make veryclean at the
  233.         top of <top>/src to make sure that the naming service stubs are
  234.         regenerated.
  235.  
  236.  
  237. Last minute news
  238. ================
  239.  
  240. - For the moment, connection screening using tcpwrapper is only available
  241.   on linux, solaris and digital unix. The build process on other platforms
  242.   still have to be sorted.
  243.  
  244.